\section{Introduction}
\src{DockingFrames} is an open source Java Swing framework published under the LGPL (lesser GNU public license). This means you are allowed to use \linebreak \src{DockingFrames} in any way you like. However if you modify the framework you are required to distribute the modified source code together with your new library.

This document introduces you to the basic concepts of \src{Core}. Naturally it cannot cover all the details, you should also have a look into the API documentation \src{http://dock.javaforge.com/doc.html}, the tutorial project and the forum on \src{http://forum.byte-welt.net/}.

\subsection{Core vs Common}
\src{DockingFrames} consists of two projects, \src{Core} and \src{Common} (the libraries \linebreak \src{docking-frames-core.jar} and \src{docking-frames-common.jar}). The important thing first: clients should use \src{Common} whenever possible.

\src{Core} provides the functionality, all the code that is required to show things on the screen and to interact with them. The content of \src{Core} is very generic, and while the API allows to implement many features, \src{Core} itself does not provide them.

\src{Common} provides an advanced default setup of \src{Core}. Features that are \emph{possible} in \src{Core}, are \emph{implemented} in \src{Common}. The API of \src{Common} is more restricted, but at the same time more easy to use.

If you are uncertain which API to take, consider these tipps:
\begin{itemize}
 \item If using \src{Common}, the API of \src{Core} is available as well.
 \item If you want to implement new functionality that does not yet exist in either project, then you should start with \src{Core}.
 \item Everyone else who just wants to get an application running in a reasonable amount of time, and is not interested in over-the-top customization, will be much happier using \src{Common}.
 \item If you are still not certain: use \src{Common}.
\end{itemize}

\infobox{Clients should make use of the \src{Common} project. In order to do so the libraries \src{docking-frames-core.jar} and \src{docking-frames-common.jar} have to be included in the classpath.}

\subsection{Use cases}
What does the framework do? \src{DockingFrames} manages the layout of your graphical user interface. It allows the user to rearrange your user interface in the way he or she likes it. All you need to do is to group your controles in small panels (called \src{Dockables}).

For which application can it be used? In general one can say that bigger applications profit more than small ones. Also power-users will like the flexibility to set up ``their'' user interface, the common user however might be overhelmed by all the buttons and options. A typical use-case would be an application which can present so many data to the user that one screen is not enough. With a modifiable user interface the user can easily filter the data and blend out the graphs, panels and buttons he does not need.

\subsection{Other frameworks}
There are at least 10 other docking frameworks for Java. As with any complex software it is impossible to say which of them is the best one. But there are some features which make sure \src{DockingFrames} is one of the better ones:

\begin{itemize}
 \item The licence, you can use the framework without paying a fee nor are you required to open source your entire project.
 \item It is pure \src{Swing}, it does not have any dependencies to other libraries. It does not force you to use some special design pattern or set up some cryptic configuration files.
 \item It does support unsigned applets (does anyone use them anymore?) and webstart.
 \item Multiple instances can run independent from each other. Sounds trivial, but there are many libraries which cannot handle this case. This design has benefits, for example a preference dialog can easily show a preview. The preview is just another instance and any properties only affects this independent instance.
 \item Much control for the client. You can change almost anything to your likings. Unfortunatelly this is not always easy as some properties are hidden deep in the framework. On the bright side you are now reading the document which tells you how to modify some of the modules.
\end{itemize}


\subsection{Notation}
This document uses the following style-guide:

\begin{itemize}
 \item ``Technical things'' like class names and project names are written mono-spaced like this: \src{java.lang.String}.
 \item Packages are not written. Almost all classes and interfaces have a unique name and with the help of the API documentation you should be able to find them easily.
 \item ``The client'' is the application using \src{DockingFrames}. ``The developer'' is you. ``The user'' is a sentient beeing using ``the client'', this might even be yourself.
 \item Additional information is given in boxes like the ones below.
\end{itemize}

\infobox{Tips and tricks are listed in boxes.}

\warningbox{Important notes and warnings are listed in boxes like this one.}

\classbox{Implementation details, especially lists of class names, are written in boxes like this.}

\designbox{These boxes explain \textit{why} some thing was designed the way it is. This might either contain some bit of history or an explanation why some awkward design is not as bad as it first looks.}

\codebox{Examples in the tutorial application are mentioned in these boxes.}

\subsection{Design principles}
In order to understand \src{Core} it helps to know what the basic design is. These design principles are applied through the entire framework. Most modules follow this principles, altough there are a few exceptions in old code.

\begin{itemize}
 \item The usage of \src{static} variables is discouraged. There are no global variables, all components must be built in a way that multiple instances can be run by the same classloader at the same time independently from each other.
 \item Communication through interfaces and usage of factories. Especialy newer code makes heavy use of factories and interfaces to keep classes independent from each other. This also means that the keyword \src{instanceof} is to be used rarely.
 \item Strong typesafty. For the client is should be impossible to smuggle an object of the wrong type into the framework, there should never be a \src{ClassCastExceptions}.
 \item Apply properties eagerly. This means that if the client changes some property it is applied before the client continous its work. This makes some parts of the framework more complex, but in the long run it adds a lot of flexibility.
\end{itemize}

\subsection{Numbers}
In \src{Core}, there are about 80'000 lines of code, distributed in over 1700 classes and interfaces. You don't need to know all of them to get your first application to run. Ordered by their semantics, the classes can be collected in groups:

\begin{description}
 \item[Control group] Long living objects which control the behavior of the user interface. For example the object handling drag \& drop is created once and remains until the application shuts down.
 \item[Swing tree group] Objects that are actually seen by the user because they are some kind of \src{java.awt.Component}. These objects build a tree, the objects from the \src{control group} can be seen as roots in this tree. Clients, or the framework itself, frequently reorganizes this tree.
 \item[Theme group] Objects responsible for painting the user interface. Sometimes these classes are big and complex, but they never are important. They can always be replaced with some other painting code.
 \item[Support group] Various small classes which do not fit into the other groups. These objects often have a short lifetime and can do exactly one task. A factory would be a good example.
\end{description}

\infobox{
Comparing the sizes (number of lines) of these groups the following numbers are seen:
\begin{center}
\begin{tabular}{lr}
Control group & 10\%\\
Swing tree group & 30\%\\
Theme group & 20\%\\
Support group & 40\%
\end{tabular}
\end{center}
}